Skip to main content

Paymasters

Paymasters are a key component of the Account Abstraction ecosystem, enabling gasless transactions by sponsoring the gas fees on behalf of users.

What is a Paymaster?​

A Paymaster is a smart contract that decides whether to sponsor a user's transaction and how to pay for it. It can implement various business models, such as:

  • Sponsoring all transactions for certain users
  • Accepting ERC-20 tokens as payment for gas
  • Implementing subscription-based models
  • Offering free transactions with certain conditions

How Paymasters Work​

  1. The user creates a UserOperation (a transaction request)
  2. The UserOperation is sent to the Paymaster for approval
  3. The Paymaster verifies if it will sponsor the transaction
  4. If approved, the Paymaster signs the transaction and adds its details
  5. The bundler includes the transaction in a bundle for execution

Using Paymasters with 0xGasless​

The 0xGasless SDK handles Paymaster interactions transparently:

// Create a transaction with Paymaster sponsorship
const tx = await wallet.transfer({
to: '0xRecipientAddress',
token: '0xTokenContractAddress',
amount: '0.01',
usePaymaster: true, // Enable Paymaster sponsorship
});
// For token-based gas payment
const tx = await wallet.transfer({
to: '0xRecipientAddress',
token: 'native',
amount: '0.01',
paymentToken: '0xUSDCAddress', // Pay gas fees with USDC
});

Types of Paymasters​

Verifying Paymaster​

The Verifying Paymaster requires a signature to validate the UserOperation. This signature can be obtained from a server after performing any necessary verification checks.

// Initialize a Verifying Paymaster
const verifyingPaymaster = new VerifyingPaymaster({
paymasterUrl: "https://paymaster.0xgasless.com/api/v1/paymaster/",
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});
// Use the paymaster for a transaction
const result = await smartAccount.sendTransaction({
to: recipient,
data: callData,
paymasterServiceData: {
paymaster: verifyingPaymaster,
// Optional: Custom data required by the paymaster
paymasterData: {
sessionId: "your-session-id",
policyId: "your-policy-id"
}
}
});

Token Paymaster​

The Token Paymaster allows users to pay for gas fees using ERC-20 tokens instead of the native blockchain currency. This is particularly useful for users who don't hold ETH but have other tokens.

// Initialize a Token Paymaster
const tokenPaymaster = new TokenPaymaster({
tokenAddress: "0xUSDCTokenAddress",
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});
// Use the token paymaster for a transaction
const result = await smartAccount.sendTransaction({
to: recipient,
data: callData,
paymasterServiceData: {
paymaster: tokenPaymaster,
paymasterData: {
tokenGasPrice: "1000000000" // Token price in wei
}
}
});

ERC-20 Transfer with Token Paymaster​

Here's an example of transferring ERC-20 tokens while using another token to pay for gas:

import { TokenPaymaster } from "@0xgasless/smart-account";
import { encodeFunctionData, parseAbi } from "viem";

// ERC-20 token to transfer
const tokenToTransfer = "0xTokenToTransferAddress";
// Token to use for gas payment
const gasToken = "0xGasTokenAddress";

// Initialize token paymaster
const tokenPaymaster = new TokenPaymaster({
tokenAddress: gasToken,
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});

// Encode ERC-20 transfer call
const transferAbi = parseAbi(["function transfer(address to, uint256 amount)"]);
const transferCalldata = encodeFunctionData({
abi: transferAbi,
functionName: "transfer",
args: [recipientAddress, "1000000000000000000"] // 1 token with 18 decimals
});

// Send transaction using token paymaster
const txResponse = await smartAccount.sendTransaction({
to: tokenToTransfer,
data: transferCalldata,
paymasterServiceData: {
paymaster: tokenPaymaster
}
});

console.log("Transaction Hash:", await txResponse.waitForTxHash());

0xGasless Paymaster Dashboard​

0xGasless provides a comprehensive dashboard for managing your paymasters. Visit https://dashboard.0xgasless.com to:

  • Create new paymasters
  • Manage paymaster funds

Best Practices​

  1. Security First: Always validate UserOperations before sponsoring them to prevent abuse
  2. Gas Efficiency: Implement gas-efficient validation logic in your paymasters
  3. Fallback Mechanism: Have a fallback mechanism if paymaster funds are depleted
  4. Monitoring: Set up alerts for low paymaster balances
  5. Rate Limiting: Implement rate limiting to prevent abuse

Troubleshooting​

Common Issues​

  • Insufficient Paymaster Balance: Ensure your paymaster contract has sufficient funds
  • Validation Failure: Check that the UserOperation meets all validation criteria
  • Gas Estimation Errors: Verify gas parameters are set correctly
  • Signature Verification Issues: Ensure signatures are created and verified correctly

For more assistance with paymasters, visit our Discord community or contact our support team.